event_request
Advanced tools
A highly customizable backend server in NodeJs. Any feedback is most welcome!
CHANGELOG || BENCHMARKS || BOARD
// Framework Singleton instance
const app = require( 'event_request' )();
// Add a new Route
app.get( '/', ( event ) => {
event.send( '<h1>Hello World!</h1>' );
});
// Start Listening
app.listen( 80, () => {
app.Loggur.log( 'Server started' );
});
The framework has a web server Singleton instance that you can fetch from anywhere using:
// First way
const app = require( 'event_request' )();
// Second way ( you can use this when you want to fetch multiple things from the framework )
const { App } = require( 'event_request' );
const app = App();
const { Server, Loggur } = require( 'event_request' );
// With this setup you'll have to work only with the variables appOne and appTwo. You cannot call App() to get any of them in different parts of the project
// This can be remedied a bit by creating routers in different controllers and then exporting them to be later on added
const appOne = new Server();
const appTwo = new Server();
// Add a new Route
appOne.get( '/', ( event ) => {
event.send( '<h1>Hello World!</h1>' );
});
// Add a new Route
appTwo.get( '/', ( event ) => {
event.send( '<h1>Hello World x2!</h1>' );
});
appOne.listen( 3334, () => {
Loggur.log( 'Server one started at port: 3334' );
});
appTwo.listen( 3335, () => {
Loggur.log( 'Server two started at port: 3335' );
});
const http = require( 'http' );
const App = require( 'event_request' );
const app = require( 'event_request' )();
const server = http.createServer( app.attach() );
// No problem adding routes like this
App().get( '/',( event ) => {
event.send( 'ok' );
});
// OR like this
app.get( '/test',( event ) => {
event.send( 'ok' );
});
server.listen( '80',() => {
app.Loggur.log( 'Server is up and running on port 80' )
});
#Properties exported by the Module: App, // The Singleton Instance of the Framework that can be used to retrieve the Web Server at any point
Server, // The Server of the framework. This is just the class and not the actual isntance. Use this only if you want to create multiple servers
Testing, // Testing tools ( Mock, Tester( constructor ), logger( logger used by the testing suite ), test( function to use to add tests ), runAllTests( way to run all tests added by test )
Logging, // Contains helpful logging functions
Loggur, // Easier access to the Logging.Loggur instance
#Getting started:
The Framework uses the "Singleton" design pattern to create a web server that can be retrieved from anywhere. When requiring the module a callback is returned that if called will return the instance:
const app = require( 'event_request' )();
Middlewares are callbacks attached to specific routes. They are called in order of addition. Global middlewares are the same as normal middlewares but they are defined differently than the normal middlewares and are attached to them. They are called before the middleware they are attached to.
Dynamic Middlewares are added together with the Global Middlewares but they are functions ( or an array of functions ). They can be used to attach dynamic functionality to routes
EventRequest is an object passed to each middleware. It holds all data about the request and has a lot of helpful functionality used for sending responses.
The framework has a set of components. These components are individual and can be used outside of the framework.
The framework also has a set of plugins that are pre included. Each Plugin modifies the Server / Event Request a bit and "plugs in" new functionality.
#Components:
#Plugins:
#Router and Routing
####Functions exported by the Router:
static matchRoute( String requestedRoute, String|RegExp route, Object matchedParams ={} ): Boolean
matchRoute( String requestedRoute, String|RegExp route, Object matchedParams ={} ): Boolean
static matchMethod( String requestedMethod, String|Array|RegExp method )
matchMethod( String requestedMethod, String|Array|RegExp method )
define( String middlewareName, Function middleware ): Router
get/post/head/put/delete...( String route, Function middleware ): void
enableCaching( Boolean enable = true ): void
setKeyLimit( Number keyLimit = 5000 ): void
####Adding routes
The server has 2 ways of adding routes/middleware
You can use .post, .put, .get, .delete, .head, .patch, .copy methods from the server that accept Required parameters: ( String|RegExp route, Function handler, Array||String middlewares = [] )
ALTERNATIVELY You can use those methods with the following commands: ( Function handler, Array||String middlewares = [] ) which will add a middleware to every route
const { App, Loggur } = require( 'event_request' );
const app = App();
app.define( 'default', ( event ) => {
Loggur.log( 'Hit the default global middleware' );
event.next();
});
app.define( 'defaultTwo', ( event ) => {
Loggur.log( 'Hit the second default global middleware' );
event.next();
});
app.get( ( event ) => {
Loggur.log( 'Always hits if method is get' );
event.next();
});
app.get( 'default', ( event ) => {
Loggur.log( 'After hitting the default global middleware' );
event.next();
});
app.get( ['default', 'defaultTwo'], ( event ) => {
Loggur.log( 'After hitting the default global middleware with an ARRAY!' );
event.next();
});
app.get( '/', ( event ) => {
event.send( '<h1>Hello World!</h1>');
});
app.post( '/', ( event ) => {
event.send( 'ok' );
});
app.delete( '/', ( event ) => {
event.send( 'ok' );
});
app.head( '/', ( event ) => {
event.send( 'ok' );
});
app.put( '/', ( event ) => {
event.send( 'ok' );
});
app.get( '/users/:user:', ( event ) => {
Loggur.log( event.params, null, true ); // Will print out whatever is passed in the url ( /users/John => 'John' )
event.send( event.params );
});
app.get( /\/pa/, ( event ) => {
Loggur.log( event.params, null, true );
// Will log { match: [ '/pa', index: 0, input: '/path', groups: undefined ] } if you hit the route /path
event.send( 'ok' );
});
app.listen( 80, () => {
Loggur.log( 'Server Started, try going to http://localhost and then to http://localhost/path. Don\'t forget to check the console logs ' );
});
####OBJECT CONTAINING:
handler: Function
route: String|RegExp
method: String|Array[String]
middlewares: String|Function|Array[Function]|Array[String]
The global middlewares if any to be called before this middleware
Optional if omitted none will be called
server.add accepts a object that must contain handler but route, method and middlewares are optional.
( { method: '', route: '', handler:() => {}, middlewares: [] } )
####Adding Routers:
const App = require( 'event_request' );
const router = App().Router();
router.get( '/', ( event ) => { event.send( 'ok' ); } );
App().add( router );
// OR you can add it directly to the router
// You can merge any 2 routers
const routerTwo = App().Router();
routerTwo.get( '/test', ( event ) => { event.send( 'okx2' ); } );
App().router.add( routerTwo )
App().listen( 80 );
####Adding Routers with path:
const app = require( 'event_request' )();
const routerOne = app.Router();
routerOne.get( '/route', ( event ) => {
event.send( 'ok' );
});
app.add( '/test', routerOne );
app.listen( 80, () => {
app.Loggur.log( 'If you go to http://localhost/test there will be a 404 error, but if you go to http://localhost/test/route it will return ok' );
});
const app = require( 'event_request' )();
const users = { userOne: {} };
// You can also attach the router to a route
const userRouter = app.Router();
userRouter.get( '/list', ( event ) => {
event.send( users );
});
// Add a new user, validate that the username parameter is a string
userRouter.post( '/add/:username:', app.er_validation.validate( { params: { username: 'string' } } ), ( event ) => {
users[event.params.username] = {};
event.send( event.params );
});
app.add( '/user', userRouter );
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost/user/list and after that try posting to http://localhost/user/add/John, when you fetch list again your new user should be added to the list' );
});
const app = require( 'event_request' )();
// You can also attach the router to a route
const userRouter = app.Router();
userRouter.get( /\/path/, ( event ) => {
event.send( event.params );
});
app.add( '/user', userRouter );
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost/user/path and then to http://localhost/user/notPath' );
});
####FUNCTION:
const App = require( 'event_request' );
const routerOne = App().Router();
routerOne.add( ( event ) => {
event.send( 'ok' );
});
App().add( routerOne );
App().listen( 80, () => {
App().Loggur.log( 'Try hitting http://localhost regardless of path or method ' )
});
const app = require( 'event_request' )();
// Adding a route
app.add({
route : '/',
method : 'GET',
handler : ( event ) => {
event.send( '<h1>Hello World!</h1>' )
}
});
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost' );
});
const App = require( 'event_request' );
const app = App();
// You can create your own router
const router = app.Router();
router.add({
route : '/',
method : 'GET',
handler : ( event) => {
event.send( '<h1>Hello World</h1>' );
}
});
app.add( router );
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost' )
});
const app = require( 'event_request' )();
// Adding a middleware without a method or route
app.add( ( event ) => {
console.log( 'Should be called always!' );
event.extra = { key: 'value' };
event.next();
});
app.add( ( event ) => {
event.send( `<h1>Hello World with extra: ${JSON.stringify(event.extra)} !</h1>` );
});
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost' )
});
const App = require( 'event_request' );
// To attach a router to the server simply call the add function of the server.
// Just like you would do to add a normal route.
App().add( router );
const app = require( 'event_request' )();
// You can also get the router attached to the Server and use that directly
const serverRouter = app.router;
serverRouter.add( { handler: ( event ) => event.send( 'ok' ) } );
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost' );
});
####Router Wildcards
const { App, Loggur } = require( 'event_request' );
const app = App();
app.add({
route : '/todos/:id:',
method : 'GET',
handler: ( event) => {
Loggur.log( event.params.id );
event.send( '<h1>Hello World</h1>' );
}
});
// Or
app.get( '/todos/:id:', ( event) => {
Loggur.log( event.params.id );
event.send( '<h1>Hello World</h1>' );
});
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost' )
});
####Router Global and Dynamic middlewares:
You can define middlewares in any router or the server. Middlewares will be merged if you add a router to another router.
These global middlewares can be used to call a function before another step in the chain.You can add multiple middlewares per route.
Dynamic middlewares will accept the same parameters as Global Middlewares
When adding global middlewares to routes they can either be a single string or multiple strings in an array.
When adding Dynamic Middlewares to routes they can either be a single function or multiple functions in an array.
You can also add a mix with both dynamic and global middlewares
They are added before the handler in .app, .get, .post, etc, or using the key middlewares if using the .add method
Due to global middlewares being before the handler if you want to add a global middleware by calling get/post/etc then the first parameter CANNOT be a string. That will be interpreted as a route
const App = require( 'event_request' );
const router = App().Router();
const app = App();
router.define( 'test', ( event ) => {
app.Loggur.log( 'Middleware One!' );
event.next();
});
// Dynamic middleware
const setHeader = ( key, value ) => {
return ( event ) => {
event.setResponseHeader( key, value );
}
}
app.define( 'test2', ( event ) => {
app.Loggur.log( 'Middleware Two!' );
event.next();
});
//this will work
app.get( ['test','test2'], ( event ) => {
event.send( 'TEST' );
});
//this will NOT work !!!
app.get( 'test', ( event ) => {
event.send( 'Error', 400 );
});
//this will work !!!
app.get( ['test'], ( event ) => {
event.send( 'TEST' );
});
//this will work !!!
app.get( setHeader( 'keyOne', 'valueOne' ), ( event ) => {
event.send( 'TEST' );
});
//this will work !!!
app.get( [setHeader( 'keyOne', 'valueOne' ), 'test'], ( event ) => {
event.send( 'TEST' );
});
//this will work !!!
app.get( [setHeader( 'keyOne', 'valueOne' ), setHeader( 'keyTwo', 'valueTwo' )], ( event ) => {
event.send( 'TEST' );
});
app.get( '/', ['test','test2'], ( event ) => {
event.send( 'TEST' );
} );
app.add({
route: '/test',
method: 'GET',
middlewares: 'test',
handler: ( event ) => {
app.Loggur.log( 'Test!' );
event.send( 'Test2' );
}
});
app.add({
route: '/test',
method: 'GET',
middlewares: ['test'],
handler: ( event ) => {
app.Loggur.log( 'Test!' );
event.send( 'Test2' );
}
});
app.add({
route: '/test',
method: 'GET',
middlewares: ['test', setHeader( 'value', 'key' )],
handler: ( event ) => {
app.Loggur.log( 'Test!' );
event.send( 'Test2' );
}
});
app.add( router );
app.listen( 80, () => {
app.Loggur.log( 'Server started' );
});
The event request is an object that is created by the server and passed through every single middleware.
####Properties of eventRequest:
query: Object
path: String
response: OutgoingMessage
request: IncomingMessage
method: String
headers: Object
validation: ValidationHandler
extra: Object
cookies: Object
params: Object
block: Array
clientIp: String
finished: Boolean
errorHandler: ErrorHandler
####Functions exported by the event request:
setCookie( String name, String value, Object options = {} ): Boolean
setStatusCode( Number code ): void
_cleanUp(): void
send( mixed response = '', Number statusCode = 200, Boolean raw ): void
setResponseHeader( String key, mixed value ): void
removeResponseHeader( String key ): void
redirect( String redirectUrl, Number statusCode = 302 ): void
getRequestHeader( String key, mixed defaultValue = null ): mixed
hasRequestHeader( String key ): Boolean
isFinished(): Boolean
next( mixed err = undefined, Number code = undefined ): void
sendError( mixed error = '', Number code = 500 ): void
validate( ...args ): ValidationResult
####Events emitted by the EventRequest
cleanUp()
finished()
send( Object sendData )
Emitted when a response has been sent.
sendData contains:
setResponseHeader( Object headerData )
removeResponseHeader( Object headerData )
redirect( Object redirectData )
Emitted when a redirect response was sent
redirectData contains:
The main object of the framework.
const { App } = require( 'event_request' );
const app = App();
// You could also do
const app = require( 'request_event' )();
const { App, Loggur } = require( 'event_request' );
const app = App();
app.listen( '80', () => {
Loggur.log( 'Server is running' );
});
const { App, Loggur } = require( 'event_request' );
const app = App();
const httpServer = app.listen( '80', () => {
Loggur.log( 'Server is running' );
});
httpServer.close();
App().cleanUp();
NOTES:
This will stop the httpServer and set the internal variable of server to null
You may need to do app = App() again since the app variable is still a pointer to the old server
If you want to start the server using your own http/https server:
const http = require( 'http' );
const App = require( 'event_request' );
const app = require( 'event_request' )();
const server = http.createServer( app.attach() );
// No problem adding routes like this
App().get( '/',( event ) => {
event.send( 'ok' );
});
// OR like this
app.get( '/test',( event ) => {
event.send( 'ok' );
});
server.listen( '80',() => {
app.Loggur.log( 'Server is up and running on port 80' )
});
App() anywhere will return the same instance of the Framework.####Functions exported by the server:
getPluginManager(): PluginManager
add( Object|Route|Function route ): Server
apply( PluginInterface|Object|String plugin, Object options ): Server
getPlugin( String|PluginInterface pluginId ): PluginInterface
hasPlugin( String|PluginInterface pluginId ): Boolean
define( String middlewareName, Function Middleware ): Server
Router(): Router
attach(): Function
listen( ... args )
####Events emitted by the server
NONE
The Logging Suite exported by the module contains the following:
300 and logs up until level 600 which is the debug level.app().Loggurconst app = require( 'event_request' )();
app.Loggur.log( 'TEST' );
enableDefault(): void
disableDefault(): void
addLogger( String loggerId, Logger|Object logger ): void
getDefaultLogger(): void
log( Log||String||mixed log, Number level, Boolean isRaw ): Promise
Loggur.log( 'Log' ); // This logs by default to an error level
Loggur.log( 'Log', LOG_LEVELS.debug ); // LOG_LEVELS.debug === Number, this will log 'Log' with debug level
Loggur.log( { test: 'value' }, LOG_LEVELS.debug, true ); // This will log on debug and will try to log the data raw
setLogLevel( Number level ): void
createLogger( Object options ): Logger
logger.setLogLevel( 600 );
Loggers can be added to the main instance of the Loggur who later can be used by: Loggur.log, which will call all the loggers added to it
const { Loggur, Console, LOG_LEVELS } = require( 'event_request' ).Logging;
const logger = Loggur.createLogger({
transports : [
new Console( { logLevel : LOG_LEVELS.notice } ),
]
});
Loggur.addLogger( 'logger_id', logger );
console.log( typeof Loggur.loggers['logger_id'] !== 'undefined' );
##Logger:
####Accepted options serverName: String
transports: Array
logLevel: Number
logLevels: Object
capture: Boolean
dieOnCapture: Boolean
unhandledExceptionLevel: Number
####Functions:
log( Log||String||mixed log, Number level, Boolean isRaw ): Promise
logger.log( 'Log' ); // This logs by default to an error level
logger.log( 'Log', LOG_LEVELS.debug ); // LOG_LEVELS.debug === Number, this will log 'Log' with debug level
logger.log( { test: 'value' }, LOG_LEVELS.debug, true ); // This will log on debug and will try to log the data raw
error(): Promise || notice(): Promise || warning(): Promise || ...
logger.error( 'Log' ); // This logs by default to an error level
logger.debug( 'Log', true ); // This will log on debug and will try to log the data raw
setLogLevel( Number level ): void
addTransport( Transport transport ): Boolean
supports( Log log ): true
getUniqueId(): String
##Console
####Accepted options:
logLevel: Number
logLevels: Array
color: Boolean
logColors: Object
###File
####Accepted options:
logLevel: Number
logLevels: Array
filePath: String
const { Loggur, LOG_LEVELS, Console, File } = require( 'event_request' ).Logging;
// Create a custom Logger
const logger = Loggur.createLogger({
serverName : 'Test', // The name of the logger
logLevel : LOG_LEVELS.debug, // The logLevel for which the logger should be fired
capture : false, // Do not capture thrown errors
transports : [
new Console( { logLevel : LOG_LEVELS.notice } ), // Console logger that logs everything below notice
new File({ // File logger
logLevel : LOG_LEVELS.notice, // Logs everything below notice
filePath : '/logs/access.log', // Log to this place ( this is calculated from the root folder ( where index.js is )
logLevels : { notice : LOG_LEVELS.notice } // The Log levels that this logger can only log to ( it will only log if the message to be logged is AT notice level, combining this with the er_logging plugin that logs all request paths to a notice level, you have a nice access log. Alternatively you can log to notice yourself )
}),
new File({
logLevel : LOG_LEVELS.error,
filePath : '/logs/error_log.log',
}),
new File({
logLevel : LOG_LEVELS.debug,
filePath : '/logs/debug_log.log'
})
]
});
Loggur.addLogger( 'serverLogger', logger );
console.log( typeof Loggur.loggers['serverLogger'] !== 'undefined' );
The validation is done by using:
const app = require( 'event_request' )();
app.get( '/', ( event ) => {
const objectToValidate = { username: 'user@test.com', password: 'pass' };
// Validation shorthand
// Password will not fit the range
const resultOne = event.validate(
objectToValidate,
{
username: 'filled||string||email||max:255',
password: 'filled||string||range:6-255'
}
);
// You can also do validation like this
// Password will fit the range
const resultTwo = event.validation.validate(
objectToValidate,
{
username: 'filled||string||email||max:255',
password: 'filled||string||range:1-255'
}
);
event.send({
resultOne : {
hasValidationFailed : resultOne.hasValidationFailed(),
validationResult : resultOne.getValidationResult()
},
resultTwo : {
hasValidationFailed : resultTwo.hasValidationFailed(),
validationResult : resultTwo.getValidationResult()
}
});
});
app.listen( 80, () => {
app.Loggur.log( 'Try hitting http://localhost')
});
const validationHandler = require( 'event_request/server/components/validation/validation_handler' )
const result = validationHandler.validate(
{
key: 'value'
},
{
key: 'string||range:1-10'
}
);
console.log( result.hasValidationFailed() );
console.log( result.getValidationResult() );
skeleton must have the keys that are to be validated that point to a string of rules separated by ||
if the object to be validated is multi dimensional then you can specify the multi dimensional keys as well ( see example below )
Asserting that an input is a string|numeric|boolean will do type conversion on the input to the appropriate type. You should retrieve the value FROM the validation result for correct result
optional
filled
array
notArray
string
weakString
notString
range
min
max
isTrue
weakIsTrue
isFalse
weakIsFalse
boolean
weakBoolean
notBoolean
numeric
weakNumeric
notNumeric
date
same
different
equals
####Note: in case of an error the exact rule/s that failed will be returned, furthermore if the rules passed were malformed a special "rules" error will be returned for the field/s
When validation is done a ValidationResult is returned. It has 2 methods: getValidationResult that in case of a validation error will return an object with the fields tested mapped to the errors found. Otherwise it will be an object with the fields tested mapped to the values hasValidationFailed that returns a boolean whether there is an error
const validationHandler = require( 'event_request/server/components/validation/validation_handler' )
const body = {
username: 'test@example.com',
password: 'test',
customerNumber: 30,
address : {
street: 'Test str',
number:'64',
numberTwo: 64 // THIS WILL NOT FAIL
// numberTwo: '64' // THIS WILL FAIL since it is weakNumeric
}
}
const bodyWhereEverythingFails = {
username: 123,
password: true,
customerNumber: 'x'.repeat( 33 ),
address : {
street: 123,
number:'wrong',
numberTwo: '64'
},
extra: true
}
const skeleton = {
username : 'filled||string||email||range:6-32',
password : 'filled||string',
customerNumber: 'numeric||max:32',
address: { street: 'string', number: 'numeric', numberTwo: 'weakNumeric' },
extra : { $rules: 'optional||string', $default: 'def' }
};
const result = validationHandler.validate( body, skeleton );
const resultWithFails = validationHandler.validate( bodyWhereEverythingFails, skeleton );
console.log( 'Validiation passes:' );
console.log( result.hasValidationFailed() );
console.log( result.getValidationResult() );
console.log( '=============================' );
console.log( 'Validation fails:' );
console.log( resultWithFails.hasValidationFailed() );
console.log( resultWithFails.getValidationResult() );
// If errors were found hasValidationFailed would return true and getValidationResult will have a map
// of which input failed for whatever reason. Otherwise getValidationResult will return an object :
// { 'username':'username', 'password': 'password', 'customerNumber': 16, address: { street: 'street', number: 64, numberTwo: 62 }, extra: 'def' }
The example will validate that the username is filled is a string and is within a range of 6-32 characters It will also validate that the password is filled and is a string The customerNumber will be validated to be numeric that is lower than 32 The address will be asserted to be an object and the keys in it will be validated The extra if not passed will default to 'def'
####Validation defaults
const validationHandler = require( 'event_request/server/components/validation/validation_handler' )
//IF no values are provided then the defaults will be taken
const body = {};
const result = validationHandler.validate(
body,
{
username : { $rules: 'optional||string', $default: 'root' },
password : { $rules: 'optional||string', $default: 'toor' }
}
);
console.log( result.hasValidationFailed() );
console.log( result.getValidationResult() );
//IF the values do exist then they will be validated
const bodyTwo = { username: 'u', password: 'p' };
const resultTwo = validationHandler.validate(
bodyTwo,
{
username : { $rules: 'optional||string||min:5', $default: 'root' },
password : { $rules: 'optional||string||min:5', $default: 'toor' }
}
);
console.log( resultTwo.hasValidationFailed() );
console.log( resultTwo.getValidationResult() );
const validationHandler = require( 'event_request/server/components/validation/validation_handler' )
const dataToValidate = {
testOne : 123,
testTwo : '123',
123 : [1,2,3,4,5],
testThree : {
'deepOne' : 123,
deepTwo : {
deeperOne : 123,
deeperTwo : '123',
deeperFour : '4'
}
},
testFour : true,
testFive : 'true',
testSix : '1',
};
const result = validationHandler.validate(
dataToValidate,
{
testOne : 'string||range:2-4',
testTwo : 'numeric||range:123-124',
123 : 'array||range:4-6',
testThree : {
deepOne : 'numeric||range:122-124',
deepTwo : {
deeperOne : 'string||range:2-4',
deeperTwo : 'numeric||range:123-124',
deeperThree : { $rules: 'optional||min:2||max:5', $default: 4 },
deeperFour : { $rules: 'optional||numeric||min:2||max:5', $default: 4 }
}
},
testFour : 'boolean',
testFive : 'boolean',
testSix : 'boolean',
testSeven : { $rules: 'optional||min:2||max:5', $default: 4 }
}
);
console.log( result.hasValidationFailed() );
console.log( result.getValidationResult() );
// false
// {
// '123': [ 1, 2, 3, 4, 5 ],
// testOne: '123',
// testTwo: 123,
// testThree: {
// deepOne: 123,
// deepTwo: { deeperOne: '123', deeperTwo: 123, deeperThree: 4, deeperFour: 4 }
// },
// testFour: true,
// testFive: true,
// testSix: true,
// testSeven: 4
// }
const validationHandler = require( 'event_request/server/components/validation/validation_handler' )
const dataToValidate = {
testOne : 123,
testTwo : '123',
123 : [1,2,3,4,5],
testThree : {
'deepOne' : 123,
deepTwo : {
deeperOne : 123,
deeperTwo : '123',
deeperFour : '4'
}
},
testFour : true,
testFive : 'true',
testSix : '1',
testNine : {
weakString : 'weakString',
weakBoolean : true,
weakNumeric : 123,
weakIsTrue : true,
weakIsFalse : false,
}
};
const result = validationHandler.validate(
dataToValidate,
{
testOne : 'string||range:2-4',
testTwo : 'numeric||range:123-124',
123 : 'array||range:4-6',
testThree : {
deepOne : 'numeric||range:122-124',
deepTwo : {
deeperOne : 'string||range:2-4',
deeperTwo : 'numeric||range:123-124',
deeperThree : { $rules: 'optional||min:2||max:5', $default: 4 },
deeperFour : { $rules: 'optional||numeric||min:2||max:5', $default: 4 }
}
},
testFour : 'boolean',
testFive : 'boolean',
testSix : 'boolean',
testSeven : { $rules: 'optional||min:2||max:5', $default: 4 },
testEight : 'numeric',
testNine : {
weakString : 'weakString',
weakBoolean : 'weakBoolean',
weakNumeric : 'weakNumeric',
weakIsTrue : 'weakIsTrue',
weakIsFalse : 'weakIsFalse',
deep : {
deeper : {
deepest: 'string'
}
}
}
}
);
console.log( result.hasValidationFailed() );
console.log( result.getValidationResult() );
// true
//{ testEight: [ 'numeric' ], testNine: { deep: { deeper: deepest: ['string'] } } }
This class can be used to limit data in one way or another.
####Accepted constructor arguments:
refillAmount: Number
refillTime: Number
maxAmount: Number
prefix: String
key: String|null
dataStore: DataServer
dataStoreRefetchInterval: Number
####The class has the following functions:
async init(): void
async reset(): void
async get(): Number
async reduce( tokens = 1 ): Boolean
async isFull(): Boolean
####Example:
const LeakyBucket = require( 'event_request/server/components/rate_limiter/bucket' );
If you need to test your project, then you can use the Testing tools included in the project.
const { Testing } = require( 'event_request' );
--filter=
--silent
--debug
--dieOnFirstError=
The testing tools include a mocker. The mocker class can be retrieved with:
const { Mock } = Testing;
The exported Mock is a Function that should be used directly on the constructor of the class you want to mock. For example:
class Test { mockThis(){} };
const MockedTest = Mock( Test );
This will return the same class but with an extra _mock function added directly to it so make sure your original class does NOT have a _mock function otherwise it will be overwritten. From here you can use the _mock function to mock any other function/parameter that is attached to the 'Test' class:
const testDouble = new MockedTest();
testDouble._mock({
method : 'mockThis',
shouldReturn : ''
});
Note: As you can see when you mock a class you MUST specify what it should return from now on. You can also give instructions on what should be returned on consecutive calls to this method like so :
const testDouble = new MockedTest();
testDouble._mock({
method : 'mockThis',
onConsecutiveCalls : ['first', 'secondAndOnwards']
});
This will result in the following:
When making a mock of a class you can specify the MAX amount of times an object should be called. Since javascript uses an async approach and relies heavily on callbacks, a minimum cannot be set.
const testDouble = new MockedTest();
testDouble._mock({
method : 'mockThis',
shouldReturn : '',
called : 1
});
This way if the method mockThis is called more than once an error will be thrown.
You can also Specify the arguments that should be provided to the mocked method like so:
const testDouble = new MockedTest();
testDouble._mock({
method : 'mockThis',
shouldReturn : '',
called : 1,
with: [
[ 'firstArgument', 'secondArgument' ],
[ 'secondCallFirstArgument', 'secondCallSecondArgument' ],
[ 'iWantToCheckThis', undefined ],
[ undefined, 'iWantToCheckThis' ]
]
});
The 'with' option accepts an array of arrays where each array in the with array is a call. Again if it's called more than the times the with arguments, the last one will be returned. In case of mismatch an Error will be thrown. If you do not want the mocker to check one of the arguments, then undefined should be passed
If you wan an environment to run your tests then you can use the test and runAllTests provided by the testing tools:
const { test, runAllTests } = TestingTools;
The 'runAllTests' function accepts an object that accepts the following options:
dieOnFirstError: Boolean
debug: Boolean
silent: Boolean
filter: String
callback: Function
###The 'test' function accepts an object with the following options:
message: String
skipped: Boolean
incomplete: Boolean
dataProvider: Array
test: Function
test({
message : 'This test should pass',
dataProvier : [
['first', 2 ],
['firstTwo', 21 ],
],
test : ( done, first, second ) => {
console.log( first ); //this will log 'first', then on the second iterration 'firstTwo'
console.log( second ); //this will log 2, then on the second iterration 21
done()
}
});
const { Tester } = TestingTools;
let tester = new Tester();
###Mocker You can also use the Mocker class by:
Mocker( classToMock, methodToMockOptions )
The TestingTools export:
#ErrorHandler
####Accepted Options:
NONE
####Events:
on_error: ( mixed error )
####Functions:
handleError( EventRequest event, Error error, Number code = 500 ): void
_getErrorToEmit( Error error ): mixed
_formatError( Error error ): mixed
_sendError( Error error ): mixed
####Attached Functionality:
event.errorHandler: ErrorHandler
####Example:
const App = require( 'event_request' );
const app = App();
app.add(( event ) => {
event.sendError( 'Error', 500 ); // This will call the error Handler
// event.next( 'Error', 500 ); // This will call the error Handler
// event.send( 'Error', 500 ); // This will !!NOT!! call the error Handler
});
app.listen( 80 );
#BodyParser
NONE
supports( EventRequest event ): Boolean
parse( EventRequest event ): Promise: Object
const BodyParserPlugin = require( 'event_request/server/plugins/available_plugins/body_parser_plugin' );
class CustomBodyParser
{
parse(){} // define logic
supports(){} // define logic
}
// The CustomBodyParser is the class and the options are the end are the parameters to be passed to the class
// This is done because A new body parser will be created on each request
const plugin = new BodyParserPlugin( CustomBodyParser, 'custom_body_parser', { optionOne: 123, optionTwo: 'value' } );
const DataServer = require( 'event_request/server/components/caching/data_server' );
console.log( DataServer );
console.log( new DataServer( options ) );
ttl: Number
persistPath: String
persistInterval: Number
gcInterval: Number
persist: Boolean
The DataServer provides a set of methods that have to be implemented if you want to create your own Caching server to be integrated with other plugins.
_saveDataError( Error error )
_saveData()
stop()
stop(): void
_stop(): void
_configure: void
_setUpPersistence(): void
get( String key, Object options = {} ): Promise: Object|null
_get( String key, Object options ): Promise: mixed|null
set( String key, mixed value, Number ttl = 0, Object options = {} ): Promise: Object|null
_set( String key, mixed value, Number ttl, Object options ): Promise: Object|null
_makeDataSet( String key, mixed value, Number ttl, Boolean persist ): Object
{ key, value, ttl, expirationDate, persist };touch( String key, Number ttl = 0, Object options = {} ): Promise: Boolean
_touch( String key, Number ttl, Object options ): Promise: Boolean
decrement( String key, Number value = 1, Object options = {} ): Promise: Number|null
_decrement( String key, Number value, Object options ): Promise: Number|null
increment( String key, Number value = 1, Object options = {} ): Promise: Number|null
_increment( String key, Number value, Object options ): Promise: Number|null
delete( String key, Object options = {} ): Promise: Boolean
_delete( String key, Object options ): Promise: Boolean
lock( String key, Object options = {} ): Promise: Boolean
_lock( String key, Object options ): Promise: Boolean
unlock( String key, Object options = {} ): Promise: Boolean
_unlock( String key, Object options ): Promise: Boolean
_garbageCollect(): void
_saveData(): void
_loadData(): void
_getExpirationDateFromTtl( Number ttl = -1 ): Number
Used for development purposes:
length(): Number
const DataServerMap = require( 'event_request/server/components/caching/data_server_map' );
console.log( DataServerMap );
console.log( new DataServerMap( options ) );
ttl: Number
persistPath: String
persistInterval: Number
gcInterval: Number
persist: Boolean
useBigMap: Boolean
_saveDataError( Error error )
_saveData()
stop()
_stop(): void
_configure: void
_setUpPersistence(): void
_get( String key, Object options ): Promise: mixed|null
_set( String key, mixed value, Number ttl, Object options ): Promise: Object|null
_touch( String key, Number ttl, Object options ): Promise: Boolean
_decrement( String key, Number value, Object options ): Promise: Number|null
_increment( String key, Number value, Object options ): Promise: Number|null
_delete( String key, Object options ): Promise: Boolean
_lock( String key, Object options ): Promise: Boolean
_unlock( String key, Object options ): Promise: Boolean
_garbageCollect(): void
_saveData(): void
_loadData(): void
Used for development purposes:
length(): Number
#BigMap
const PluginInterface = require( 'event_request/server/plugins/plugin_interface' );
Server {
...
er_timeout,
er_env,
er_rate_limits,
er_static_resources,
er_data_server,
er_templating_engine,
er_file_stream,
er_logger,
er_session,
er_security,
er_cors,
er_response_cache,
er_body_parser_json,
er_body_parser_form,
er_body_parser_multipart,
er_body_parser_raw,
er_validation,
}
er_const App = require( 'event_request' );
const app = App();
const PluginManager = app.getPluginManager();
const timeoutPlugin = PluginManager.getPlugin( 'er_timeout' );
timeoutPlugin.setOptions( { timeout : 5 * 1000 } );
app.apply( timeoutPlugin );
// app.er_timeout.setOptions( { timeout : 5 * 1000 } );
// app.apply( app.er_timeout );
// app.apply( timeoutPlugin, { timeout : 5 * 1000 } );// This will accomplish the same thing as the rows above
//
// app.apply( 'er_timeout' ); // This is also valid.
// app.apply( 'er_timeout', { timeout : 5 * 1000 } ); // This is also valid.
//
// app.apply( app.er_timeout ); // This is also valid.
// app.apply( app.er_timeout, { timeout : 5 * 1000 } ); // This is also valid.
app.get('/',() => {});
app.listen( 80, () => {
app.Loggur.log( 'Try opening http://localhost and wait for 5 seconds' )
} );
The PluginInterface has a getPluginMiddleware method that must return an array of middleware objects implementing handler, route, method keys or instances of Route.
The PluginInterface has a setOptions function that can be used to give instructions to the Plugin when it is being created and added to the event request
The PluginInterface implements a getPluginDependencies method that returns an Array of needed plugins to work. These plugins must be installed before the dependant plugin is.
The PluginInterface implements a setServerOnRuntime method that passes the server as the first and only argument. Here the plugin can interact with the server.pluginBag to store any data it seems fit or may modify the server in one way or another.
The PluginInterface implements a getPluginId method that returns the id of the plugin ( these must be unique ).
Generally plugins should not have any business logic in the constructor and rather have that in the setServerOnRuntime or getPluginMiddleware functions. This is the case because new options can be given to the plugin when attaching to the server.
This is how the flow of adding a plugin goes:
The manager can be extracted from the created Server by:
const pluginManager = server.getPluginManager();
The Plugin manager contains pre loaded plugins. You can add your own plugins to it for easy control over what is used or if you want the bootstrap of the project to be in a different place.
The plugin Manager exports the following functions:
addPlugin( plugin ) - accepts only a plugin of instance PluginInterface and only if it does not exist already otherwise throws an exception
hasPlugin( id ) - checks if a plugin with the specified id exist
removePlugin( id ) - removes a plugin
getAllPluginIds() - returns an array with all the possible plugins
getPlugin( id ) - returns a PluginInterface otherwise throw
#er_timeout
####Dependencies:
NONE
####Accepted Options:
timeout: Number
callback: Function
function callback( event )
{
event.next( `Request timed out in: ${this.timeout/1000} seconds`, 503 );
}
####Events:
clearTimeout()
####EventRequest Attached Functions
event.clearTimeout(): void
####Attached Functionality:
event.internalTimeout: Timeout
####Exported Plugin Functions:
NONE
####Example:
const App = require( 'event_request' );
const app = App();
const PluginManager = app.getPluginManager();
const timeoutPlugin = PluginManager.getPlugin( 'er_timeout' );
// timeoutPlugin.setOptions( { timeout : 2 * 1000 } );
// app.apply( timeoutPlugin );
// app.er_timeout.setOptions( { timeout : 2 * 1000 } );
// app.apply( app.er_timeout );
// app.apply( timeoutPlugin, { timeout : 2 * 1000 } );// This will accomplish the same thing as the rows above
//
// app.apply( 'er_timeout' ); // This is also valid.
// app.apply( 'er_timeout', { timeout : 2 * 1000 } ); // This is also valid.
//
// app.apply( app.er_timeout ); // This is also valid.
// app.apply( app.er_timeout, { timeout : 2 * 1000 } ); // This is also valid.
// This attaches a timeout of 2 seconds with a custom callback
app.apply( app.er_timeout, { timeout: 2 * 1000, callback: ( event ) => {
event.send( 'You timed out!', 200 );
}
});
app.get('/',() => {});
app.listen( 80, () => {
app.Loggur.log( 'Try opening http://localhost and wait for 2 seconds' )
});
#er_static_resources
####Dependencies:
NONE
####Accepted Options:
paths: Array[String] | String
####Events:
NONE
####EventRequest Attached Functions
NONE
####Attached Functionality:
NONE
####Exported Plugin Functions:
NONE
####Example:
const App = require( 'event_request' );
const app = App();
// This will serve everything in folder public and favicon.ico on the main folder
app.apply( app.er_static_resources, { paths : ['public', 'favicon.ico'] } );
//OR
// This will serve everything in folder public and favicon.ico on the main folder
app.apply( 'er_static_resources', { paths : ['public', 'favicon.ico'] } );
//OR
// This will act according to the defaults
app.apply( 'er_static_resources' );
//OR
// This will act according to the defaults
app.apply( app.er_static_resources );
//OR
const PluginManager = app.getPluginManager();
const staticResourcesPlugin = PluginManager.getPlugin( 'er_static_resources' );
// This will serve everything in folder public and favicon.ico on the main folder
staticResourcesPlugin.setOptions( { paths : ['public', 'favicon.ico'] } );
app.apply( staticResourcesPlugin );
app.listen( 80 );
#er_data_server
event.dataServer####Dependencies:
NONE
####Accepted Options:
dataServerOptions: Object
dataServer: Object
####Events:
NONE
####EventRequest Attached Functions
NONE
####Attached Functionality:
event.dataServer: DataServer
####Exported Plugin Functions:
getServer(): DataServer
####Example:
const App = require( 'event_request' );
const app = App();
app.apply( 'er_data_server' );
// OR
app.apply( app.er_data_server );
// OR if you want to pass specific parameters to the default DataServer:
app.apply( app.er_data_server, { dataServerOptions: { persist: false, ttl: 200, persistPath: '/root' } } );
app.get( '/', async ( event ) => {
const value = await event.dataServer.get( 'testKey' );
if ( value !== 'testValue' )
await event.dataServer.set( 'testKey', 'testValue' );
event.send( value )
});
app.listen( 80 , () => {
app.Loggur.log( 'Server started, try going to http://localhost twice!' );
});
#er_session
####Dependencies:
er_data_server
####Accepted Options:
ttl: Number
sessionKey: String
sidsessionIdLength: Number
isCookieSession: Boolean
####Events:
NONE
####EventRequest Attached Functions
event.initSession( Function callback ): Promise
####Attached Functionality:
event.session: Session
####The Session exports the following functions:
hasSession(): Promise: Boolean
removeSession(): Promise: void
newSession(): Promise: String||Boolean
add( String name, mixed value ): void
get( String key ): mixed
delete( String key ): void
has( String key ): Boolean
saveSession( String sessionId = currentSessionId ): Promise: Boolean
####Exported Plugin Functions:
NONE
####Example:
const { Loggur, App } = require( 'event_request' );
const app = App();
app.apply( app.er_body_parser_json );
app.apply( app.er_body_parser_form );
app.apply( app.er_body_parser_multipart );
app.apply( app.er_data_server );
app.apply( app.er_session );
// Initialize the session
app.add( async ( event ) => {
event.initSession( event.next ).catch( event.next );
});
// Redirect to login if authenticated is not true
app.add(( event ) => {
if (
event.path !== '/login'
&& ( ! event.session.has( 'authenticated' ) || event.session.get( 'authenticated' ) === false )
) {
event.redirect( '/login' );
return;
}
event.next();
});
app.post( '/login', async ( event ) => {
const result = event.validate( event.body, { username : 'filled||string', password : 'filled||string' } );
if ( result.hasValidationFailed() )
{
event.redirect( '/login' );
return;
}
const { username, password } = result.getValidationResult();
if ( username === 'username' && password === 'password' )
{
event.session.add( 'username', username );
event.session.add( 'authenticated', true );
event.redirect( '/' );
}
else
{
event.redirect( '/login' );
}
});
app.get( '/login', ( event ) => {
event.send( 'Try to post to /login with { username: "username", password: "password" } in the body. Make sure to send the cookie you get back!' );
})
app.get( '/',( event ) => {
event.send( 'LOGGED IN!' );
});
app.listen( 80, () => {
Loggur.log( 'Server started' );
});
#er_templating_engine
####Dependencies:
NONE
####Accepted Options:
engine: Object
templateDir: String
####Events:
render ( String templateName, Object variables )
####EventRequest Attached Functions
event.render( String templateName, Object variables = {}, Function errorCallback = null ): Promise
####Attached Functionality:
event.templatingEngine: TemplatingEngine
event.templateDir: String
####Exported Plugin Functions:
NONE
####Example:
const app = require( 'event_request' )();
app.apply( app.er_templating_engine, { templateDir: path.join( __dirname, './public' ) } );
// OR
app.apply( 'er_templating_engine' );
// OR
app.apply( app.er_templating_engine );
// OR
const PluginManager = server.getPluginManager();
const templatingEnginePlugin = PluginManager.getPlugin( app.er_templating_engine );
templatingEnginePlugin.setOptions( { templateDir : path.join( __dirname, './public' ), engine : someEngineConstructor } );
app.apply( templatingEnginePlugin );
// THEN
router.get( '/preview', ( event ) => {
// If you have a templating engine that supports parameters:
event.render( 'preview', { type: 'test', src: '/data' }, event.next );
// Otherwise the default one can only render html
event.render( 'preview', {}, event.next );
}
);
#er_file_stream
####Dependencies:
NONE
####Accepted Options:
NONE
####Events:
stream_start ( FileStream stream )
####EventRequest Attached Functions
event.streamFile( String file, Object options = {}, errCallback ): void
event.getFileStream( file, options = {} ): FileStream | null
####Attached Functionality:
event.fileStreamHandler: Object
####Exported Plugin Functions:
NONE
####Example:
const app = require( 'event_request' )();
const PluginManager = app.getPluginManager();
const fileStreamPlugin = PluginManager.getPlugin( 'er_file_stream' );
app.apply( fileStreamPlugin );
// OR
app.apply( app.er_file_stream );
// OR
app.apply( 'er_file_stream' );
const fs = require( 'fs' );
const app = require( 'event_request' )();
app.apply( app.er_file_stream );
app.get( '/data', ( event ) => {
const result = event.validation.validate( event.query, { file: 'filled||string||min:1' } );
const file = ! result.hasValidationFailed() ? result.getValidationResult().file : false;
if ( ! file || ! fs.existsSync( file ) )
{
event.next( 'File does not exist' );
}
else
{
// You can use this if you want to maybe pipe the file stream to a transformation stream or in general
// do something else than piping it to the event.response
event.getFileStream( file ).pipe( event.response );
}
}
);
app.get( '/dataTwo', ( event ) => {
const result = event.validation.validate( event.query, { file: 'filled||string||min:1' } );
const file = ! result.hasValidationFailed() ? result.getValidationResult().file : false;
if ( ! file || ! fs.existsSync( file ) )
{
event.next( 'File does not exist' );
}
else
{
event.streamFile( file );
}
}
);
app.listen( '80', () => {
app.Loggur.log( 'Try hitting http://localhost/data?file={someFileInTheCurrentProjectRoot}' );
});
#er_logger
####Dependencies:
NONE
####Accepted Options:
logger: Logger
attachToProcess: Boolean
####Events:
NONE
####EventRequest Attached Functions
NONE
####Attached Functionality:
process.dumpStack(): Promise
process.log( data, level ): Promise
####Exported Plugin Functions:
NONE
####Example:
const app = require( 'event_request' )();
const PluginManager = app.getPluginManager();
const loggerPlugin = PluginManager.getPlugin( 'er_logger' );
app.apply( loggerPlugin );
//OR
app.apply( 'er_logger' );
//OR
app.apply( app.er_logger, { logger: SomeCustomLogger, attachToProcess: false } );
#er_body_parser_json, er_body_parser_form, er_body_parser_multipart, er_body_parser_raw
####Dependencies:
NONE
####Accepted Options:
#####MultipartFormParser:
maxPayload: Number
tempDir: String
#####JsonBodyParser: maxPayloadLength: Number
strict: Boolean
#####RawBodyParser: maxPayloadLength: Number
#####FormBodyParser: maxPayloadLength: Number
strict: Boolean
cleanUpItemsTimeoutMS: Number
####Events:
NONE
####EventRequest Attached Functions
NONE
####Attached Functionality:
event.body: Object
event.rawBody: Object
####Exported Plugin Functions:
NONE
####Example:
const app = require( 'event_request' )();
// Add Body Parsers
app.apply( app.er_body_parser_json );
app.apply( app.er_body_parser_form );
app.apply( app.er_body_parser_multipart );
app.apply( app.er_body_parser_raw );
// Add body parsers with custom options
app.apply( app.er_body_parser_json, { maxPayloadLength: 104857600, strict: false } );
app.apply( app.er_body_parser_form, { maxPayloadLength: 10485760, strict: false } );
app.apply( app.er_body_parser_multipart, { cleanUpItemsTimeoutMS: 100, maxPayload: 0, tempDir: path.join( PROJECT_ROOT, '/Uploads' ) } );
app.apply( app.er_body_parser_raw, { maxPayloadLength: 10485760 } );
app.post( '/submit', ( event ) => {
console.log( event.body );
console.log( event.rawBody );
event.send();
});
#er_response_cache Adds a response caching mechanism.
####Dependencies:
er_data_server
####Accepted Options:
NONE
####Events:
NONE
####EventRequest Attached Functions
NONE
####Attached Functionality:
Middleware: cache.request
event.cacheCurrentRequest(): Promise
####Exported Plugin Functions:
NONE
####Example:
const app = require( 'event_request' )();
app.apply( app.er_data_server );
app.apply( app.er_response_cache );
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// call event.cacheCurrentRequest() where you want to cache.
app.add({
route : '/',
method : 'GET',
handler : ( event ) => {
event.cacheCurrentRequest().catch( event.next );
// Nothing else should be done after calling cache current request in the same middleware, a new one needs to be added
// cacheCurrentRequest calls next inside it if it is not cached and caches it, if it is cached, then it will return the cached result
}
});
// OR
// When setting a request to be cached, ttl and useIp may be passed that will overwrite the default options
// app.add( ( event ) => {
// //**useIp** -> whether the user Ip should be included when caching. This allows PER USER cache. -> Defaults to false
// //**ttl** -> time to live for the record. Defaults to 60 * 5000 ms
//
// event.cacheCurrentRequest( { ttl: 20 * 1000, useIp: true } ).catch( event.next );
// });
let counter = 0;
// call event.cacheCurrentRequest() where you want to cache.
app.add({
route : '/',
method : 'GET',
handler : ( event ) => {
counter ++;
if ( counter > 1 )
event.send( 'NOT CACHED', 500 );
event.send( 'ok' );
}
});
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// OR You can create your own middleware that will be added to all requests
// you want to cache, no need to do it separately
let counterTwo = 0;
let counterThree = 0;
app.get( /\/test/, ( event ) => {
event.cacheCurrentRequest().catch( event.next );
});
app.get( '/testTwo', async ( event ) => {
counterTwo ++;
if ( counterTwo > 1 )
event.send( 'NOT CACHED', 500 );
event.send( 'ok' );
});
app.get( '/testThree', async ( event ) => {
counterThree ++;
if ( counterThree > 1 )
event.send( 'NOT CACHED', 500 );
event.send( 'ok' );
});
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
let counterFour = 0;
// You can add it via a middleware to a specific route
app.get( '/testFour', 'cache.request', ( event )=>
{
counterFour ++;
if ( counterFour > 1 )
event.send( 'NOT CACHED', 500 );
event.send( 'ok' );
}
);
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost, http://localhost/testTwo, http://localhost/testThree, http://localhost/testFour' );
});
#er_env
####Dependencies:
NONE
####Accepted Options:
fileLocation: String
####Events:
NONE
####EventRequest Attached Functions
NONE
####Attached Functionality:
NONE
####Exported Plugin Functions:
NONE
####Example:
KEY=TESTconst app = require( 'event_request' )();
app.apply( 'er_env' );
console.log( process.env );
console.log( process.env.KEY );
#er_validation
####Dependencies:
NONE
####Accepted Options:
failureCallback: Function
####Events:
NONE
####EventRequest Attached Functions
NONE
####Attached Functionality:
NONE
####Exported Plugin Functions:
validate( Object validationRules, Function failureCallback): Function
####Example:
const app = require( 'event_request' )();
app.apply( app.er_body_parser_multipart );
// This will validate the query parameters
app.get( '/',
app.er_validation.validate( { query : { testKey: 'numeric||min:1||max:255' } } ),
( event ) => {
event.send( { query: event.query } );
}
);
app.listen( 80, () => {
app.Loggur.log(
'Server started on port 80. Try going to http://localhost?testKey=5. Change the value for testKey to get a different response.'
);
}
);
const app = require( 'event_request' )();
// This will validate the query parameters and will call the error callback
app.get( '/',
app.er_validation.validate(
{ query : { testKey: 'numeric||min:1||max:255' } },
( event, validationParameter, validationResult ) => {
app.Loggur.log( validationParameter, null, true );
app.Loggur.log( validationResult, null, true );
event.send( 'ok' );
}
),
( event ) => {
event.send( { query: event.query } );
}
);
app.listen( 80, () => {
app.Loggur.log(
'Server started on port 80. Try going to http://localhost?testKey=5. Change the value for testKey to get a different response.'
);
}
);
const app = require( 'event_request' )();
// Alternatively you can do:
app.er_validation.setOptions({
failureCallback: ( event, validationParameter, validationResult ) => {
app.Loggur.log( validationParameter, null, true );
app.Loggur.log( validationResult, null, true );
event.send( 'DEFAULT' );
}
});
app.apply( app.er_body_parser_multipart );
app.apply( app.er_body_parser_json );
app.apply( app.er_body_parser_form );
// This will validate the query parameters and will call the error callback
app.get( '/',
app.er_validation.validate(
{ query : { testKey: 'numeric||min:1||max:255' } },
( event, validationParameter, validationResult ) => {
app.Loggur.log( validationParameter, null, true );
app.Loggur.log( validationResult, null, true );
event.send( 'CUSTOM' );
}
),
( event ) => {
event.send( { query: event.query } );
}
);
app.listen( 80, () => {
app.Loggur.log(
'Server started on port 80. Try going to http://localhost?testKey=5. Change the value for testKey to get a different response.'
);
}
);
const app = require( 'event_request' )();
app.apply(
app.er_validation,
{
failureCallback: ( event, validationParameter, validationResult ) => {
app.Loggur.log( validationParameter, null, true );
app.Loggur.log( validationResult, null, true );
event.send( 'ok' );
}
}
);
app.apply( app.er_body_parser_multipart );
app.apply( app.er_body_parser_json );
app.apply( app.er_body_parser_form );
// This will validate the query parameters and the body and will call the error callback
app.post( '/',
app.er_validation.validate(
{ query : { testKey: 'numeric||min:1||max:255' }, body: { test: 'numeric||range:1-255' } }
),
( event ) => {
event.send( { query: event.query, body: event.body } );
}
);
// This will validate the query parameters and will call the error callback
app.get( '/',
app.er_validation.validate(
{ query : { testKey: 'numeric||min:1||max:255' } }
),
( event ) => {
event.send( { query: event.query } );
}
);
app.listen( 80, () => {
app.Loggur.log(
'Server started on port 80. Try going to http://localhost?testKey=5. Change the value for testKey to'
+ ' get a different response. Try posting to http://localhost?testKey=5 with a body: test=5. Change the'
+ ' value for test in the body to get a different response'
);
}
);
#er_cors
const defaults = {
'Access-Control-Allow-Origin': '*',
'Access-Control-Allow-Headers': '*',
'Access-Control-Allow-Methods': 'POST, PUT, GET, DELETE, HEAD, PATCH, COPY',
};
####Dependencies:
NONE
####Accepted Options:
origin: String
headers: Array
exposedHeader: Array
methods: Array
status: Number
credentials: Boolean
maxAge: Number
####Events:
NONE
####EventRequest Attached Functions
NONE
####Attached Functionality:
NONE
####Exported Plugin Functions:
NONE
####Example:
const app = require( 'event_request' )();
app.apply( app.er_cors, {
origin: 'http://example.com',
methods: ['GET', 'POST'],
headers: ['Accepts', 'X-Requested-With'],
exposedHeaders: ['Accepts'],
status: 200,
maxAge: 200,
credentials: true,
});
app.add(( event ) => {
event.send( event.response.getHeaders() );
});
app.listen( 80, () => {
app.Loggur.log( 'Server started, try going to http://localhost and check the body. It will have the returned headers!' )
});
####Dependencies:
NONE
####Accepted Options:
fileLocation
dataStore
rules
useFile
####Events:
rateLimited( String policy, Object rule )
####EventRequest Attached Functions
NONE
####Attached Functionality:
event.rateLimited: Boolean
eventRequest.erRateLimitRules: Array
####Exported Plugin Functions:
rateLimit( Object rule ): Function
####Notes: If you want to create custom rate limiting you can get er_rate_limits plugin and use getNewBucketFromOptions to get a new bucket, given options for it options['maxAmount'] options['refillTime'] options['refillAmount']
Rate limit can be applied to different routes and different HTTP methods Rate limit rule options:
path: String
methods: Array
maxAmount: Number
refillTime: Number
refillAmount: Number
policy: String
delayTime: Number
delayRetries: Number
stopPropagation: Boolean
ipLimit: Boolean
####POLICIES:
PERMISSIVE_POLICY = 'permissive';
This policy will let the client connect freely but a flag will be set that it was rate limited
CONNECTION_DELAY_POLICY = 'connection_delay';
This policy will rate limit normally the request and will hold the connection until a token is freed If this is the policy specified then delayTime and delayRetries must be given. This will be the time after a check should be made if there is a free token. The first connection delay policy hit in the case of many will be used to determine the delay time but all buckets affected by such a connection delay will be affected
STRICT_POLICY = 'strict';
This policy will instantly reject if there are not enough tokens and return an empty response with a 429 header. This will also include a Retry-After header. If this policy is triggered, stopPropagation will be ignored and the request will be immediately canceled
####Example:
[
{
"path": "",
"methods": [],
"maxAmount": 10000,
"refillTime": 10,
"refillAmount": 1000,
"policy": "connection_delay",
"delayTime": 3,
"delayRetries": 5,
"stopPropagation": false,
"ipLimit": false
}
]
const app = require( 'event_request' )();
const rule = {
path : '/rate',
methods : ['GET'],
maxAmount :3,
refillTime :10,
refillAmount :2,
policy : 'strict'
};
app.apply( app.er_rate_limits, { rules: [rule] } );
app.get( '/rate', ( event ) => {
event.send( 'ok' );
});
app.listen( 80, () => {
app.Loggur.log( 'Server started at port 80, try visiting http://localhost:80/rate a 4 times' );
});
const { Server } = require( 'event_request' );
const DataServer = require( 'event_request/server/components/caching/data_server' );
const dataStore = new DataServer( { persist: false, ttl: 90000 } );
const appOne = new Server();
const appTwo = new Server();
const rule = {
path : '/rate',
methods : ['GET'],
maxAmount :3,
refillTime :10,
refillAmount :2,
policy : 'strict'
};
appOne.apply( appOne.er_rate_limits, { dataStore, rules: [rule] } );
appTwo.apply( appTwo.er_rate_limits, { dataStore, rules: [rule] } );
appOne.get( '/rate', ( event ) => {
event.send( 'ok' );
});
appTwo.get( '/rate', ( event ) => {
event.send( 'ok' );
});
appOne.listen( 80, () => {
appOne.Loggur.log( 'Server One started at port 80, try visiting http://localhost:80/rate 2 times' )
});
appTwo.listen( 81, () => {
appTwo.Loggur.log( 'Server Two started at port 81, try visiting http://localhost:81/rate 2 times' )
});
const app = require( 'event_request' )();
const rule = {
"maxAmount":3,
"refillTime":100,
"refillAmount":2,
"policy": 'strict'
};
// No need to apply this
app.apply( app.er_rate_limits );
app.get( '/testRoute', app.er_rate_limits.rateLimit( rule ), ( event ) => {
event.send( 'ok' );
});
const ruleTwo = {
"maxAmount":1,
"refillTime":100,
"refillAmount":1,
"policy": 'permissive'
};
app.get( '/testRouteTwo', [
app.er_rate_limits.rateLimit( ruleTwo ),
app.er_rate_limits.rateLimit( rule )
], ( event ) => {
app.Loggur.log( event.erRateLimitRules, undefined, true );
event.send( `You have been rate limited by permissive: ${event.rateLimited}` );
});
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost/testRoute and then to http://localhost/testRouteTwo and refreshing a few times' );
});
const app = require( 'event_request' )();
const rules = [
{
"path": "/",
"methods": [],
"maxAmount": 2,
"refillTime": 5,
"refillAmount": 1,
"policy": "strict"
},
{
"path": "/connection",
"methods": [],
"maxAmount": 2,
"refillTime": 5,
"refillAmount": 1,
"policy": "connection_delay",
"delayTime": 3,
"delayRetries": 5,
"ipLimit": true
},
{
"path": "/permissive",
"methods": [],
"maxAmount": 2,
"refillTime": 5,
"refillAmount": 1,
"policy": "permissive",
"ipLimit": true
},
];
app.apply( app.er_rate_limits, { rules } );
app.get( '/', ( event ) => {
event.send( 'You have been allowed in!' );
});
app.get( '/connection', ( event ) => {
event.send( 'You have been allowed in!' );
});
app.get( '/permissive', ( event ) => {
event.send( `You have been limited: ${event.rateLimited}` );
});
app.listen( 80, () => {
app.Loggur.log( 'Try going to http://localhost and hit refresh a few times. You will get an error but after a while you will be let back in.' );
app.Loggur.log( 'Try going to http://localhost/connection and hit refresh a few times. The site will be stuck loading for a while but will eventually connect.' );
app.Loggur.log( 'Try going to http://localhost/permissive and hit refresh a few times. You will not get an error but you will see a flag is set' );
});
#er_security
####Dependencies:
NONE
####Accepted Options:
build: Boolean
csp: Object
hsts: Object
ect: Object
cto: Object
####Events:
NONE
####EventRequest Attached Functions
event.$security.build(): void
####Attached Functionality:
event.$security: Object
event.$security.csp: ContentSecurityPolicy
event.$security.cto: ContentTypeOptions
event.$security.hsts: HttpStrictTransportSecurity
event.$security.ect: ExpectCT
####Exported Plugin Functions:
NONE
####Objects:
#####HTTP Strict Transport Security
enabled: Boolean
maxAge: Number
includeSubDomains: Boolean
preload: Boolean
getHeader(): String
build(): String
setMaxAge( Number maxAge ): void
setEnabled( Boolean enabled = true ): void
preload( Boolean preload = true ): void
includeSubDomains( Boolean include = true ): void
#####Content Type Options
enabled: Boolean
getHeader(): String
build(): String
#####Expect-CT
enabled: Boolean
maxAge: Number
enforce: Boolean
reportUri: String
setEnabled( Boolean enabled = true ): void
enforce( Boolean enforce = true ): void
setReportUri( String reportUri ): void
setMaxAge( Number maxAge ): void
getHeader(): String
build(): String
#####Content Security Policy
enabled: Boolean
directives: Object
sandbox: []self, unsafe-eval, etc without single quotesxss: Boolean
self: Boolean
sandbox: Boolean
reportUri: String
useReportTo: Boolean
xss(): void
allowPluginType( String mimeType ): void
setEnabled( Boolean enabled = true ): void
getHeader(): String
setReportOnly( String uri ): void
setReportOnlyWithReportTo( String uri ): void
enableSandbox(): void
allowSandboxValue( String value ): void
upgradeInsecureRequests(): void
addBaseUri( String uri ): void
addFrameAncestors( String uri ): void
addScriptSrc( String uri ): void
addImgSrc( String uri ): void
addChildSrc( String uri ): void
addConnectSrc( String uri ): void
addConnectSrc( String uri ): void
addDefaultSrc( String uri ): void
enableSelf(): void
addFontSrc( String uri ): void
addFrameSrc( String uri ): void
addFrameSrc( String uri ): void
addManifestSrc( String uri ): void
addMediaSrc( String uri ): void
addObjectSrc( String uri ): void
addStyleSrc( String uri ): void
build(): String
####Example:
const app = require( 'event_request' )();
// It's a good idea to do this first before attaching any other plugins or adding routes
app.apply( app.er_security );
const app = require( 'event_request' )();
app.apply( app.er_security );
app.add(( event ) => {
event.$security.csp.enableSandbox();
event.$security.hsts.setEnabled( false );
event.$security.cto.setEnabled( false );
event.$security.ect.setMaxAge( 300 );
event.$security.ect.setReportUri( '/report/uri' );
event.$security.build();
event.send();
});
app.listen( 80, () => {
app.Loggur.log( 'Try opening http://localhost and checking the headers sent from the server!' );
});
const app = require( 'event_request' )();
app.apply( app.er_security, {
csp : {
directives : {
'font-src' : ['https://fonts.gstatic.com'],
'script-src': ['https://example.com'],
'style-src': ['https://example.com', 'unsafe-eval'],
},
xss: true
},
ect : {
maxAge: '300'
},
hsts : {
maxAge: '300',
preload: false
},
cto : {
enabled: false
},
build: true
});
app.add(( event ) => {
event.send( '' );
});
app.listen( 80, () => {
app.Loggur.log( 'Try opening http://localhost and checking the headers sent from the server!' );
});
const app = require( 'event_request' )();
app.apply( app.er_security, { csp : { xss: false } } );
app.add(( event ) => {
// self is repeated twice but will be shown only once and with single quotes
event.$security.csp.addFontSrc( 'self' );
event.$security.csp.addFontSrc( "'self'" );
event.$security.csp.addFontSrc( 'test' );
event.$security.csp.upgradeInsecureRequests();
event.$security.csp.enableSelf();
event.$security.csp.enableSandbox();
event.$security.ect.setEnabled( false );
event.$security.ect.setMaxAge( 30000 );
event.$security.hsts.setMaxAge( 300 );
// null and 'string' are invalid for max age so 300 will be left
event.$security.hsts.setMaxAge( null );
event.$security.hsts.setMaxAge( 'string' );
event.$security.hsts.preload();
event.$security.hsts.includeSubDomains( false );
event.$security.build();
// This will actually add a new script-src to the csp and will disable the cto component
event.$security.csp.addScriptSrc( 'test' );
event.$security.ect.setEnabled( true );
// This will overwrite the previous build and set the new modified headers
event.$security.build();
event.send( '' );
});
app.listen( 80, () => {
app.Loggur.log( 'Try opening http://localhost and checking the headers sent from the server!' );
});
FAQs
A Backend Server
The npm package event_request receives a total of 4 weekly downloads. As such, event_request popularity was classified as not popular.
We found that event_request demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.